Input Devices

Java 3D API Specification

JAVA 3D provides access to keyboards and mice using Java's standard API for keyboard and mouse support. Additionally, it provides access to a variety of continuous input devices such as six-degree-of-freedom (6DOF) trackers and joysticks.
Continuous input devices like 6DOF trackers and joysticks have well defined continuous inputs. Trackers produce a position and orientation that Java 3D stores internally as a transform matrix. Joysticks produce two continuous values in the range (-1.0, 1.0) that Java 3D stores internally as a transform matrix with an identity rotation (no rotation) and one of the Joystick values as the x translation and the other as the y translation component.
Unfortunately, continuous input devices do not have the same level of consistency when it comes to their associated switches or buttons. Still the number of buttons or switches attached to a particular sensing element remains constant across all sensing elements associated with a single device.

9.1 InputDevice Interface

The InputDevice interface specifies an abstract input device that a developer can use in implementing a device driver for a particular device. All implementations of an InputDevice interface must implement all of its methods. Java 3D's input device scheduler uses these methods to interact with specific devices and incorporates their input. In addition to the generic methods that all InputDevices must provide, implementations of an InputDevice will contain whatever device-specific information and methods necessary to maintain that device's proper functioning.
All input devices consist of a number of Sensor objects that have a direct one-to-one relationship with that device's physical detectors. Sensor objects serve double duty. They not only represent actual physical detectors but they also serve as abstract six-degree-of-freedom transformations that a Java 3D application can access. The Sensor class is described in more detail in the next section.

9.1.1 The Abstract Interface

All input devices implement a consistent interface that allows the initialization, processing of input, and finalization of a particular input device. A device-driver programmer would implement the following methods in whatever device-specific manner is necessary to perform the specified operations.

Constants
public static final int POLLED
public static final int STREAMING
These flags specify whether the associated device works in polled mode or streaming mode.

Methods
public abstract boolean initialize()
This method initializes the device. It returns true if initialization succeeded, false otherwise.
public abstract void setProcessingMode(int mode)
public abstract int getProcessingMode()
These methods set and retrieve this device's processing mode.
public abstract int getSensorCount()
This method returns the number of Sensor objects associated with this device.
public abstract Sensor getSensor(int sensorIndex)
This method returns the specified Sensor associated with this device.
public abstract void setNominalPositionAndOrientation()
This method sets the device's current position and orientation as the devices nominal position and orientation (establishes its reference frame relative to the "Tracker base" reference frame). This method is most useful in defining a nominal pose in immersive head-tracked situations.
public abstract void pollAndProcessInput()
This method first polls the device for data values and then processes the values received from the device.
public abstract void processStreamInput()
This method processes the device's streaming input.
public abstract void close()
This method closes the device.

9.1.2 Instantiating And Registering A New Device

A browser or applications developer must instantiate whatever system specific input devices that he or she needs and that exist on the system. This available device information typically exists in a site configuration file. The browser or application will instantiate the viewing environment as requested by the end-user.
The API for instantiating devices is site specific, but it consists of a device object with a constructor and at least all of the methods specified in the InputDevice interface.
Once instantiated, the browser or application must register the device with the Java 3D input device scheduler. The API for registering devices is specified in Section 8.7, "The View Object." The addInputDevice method introduces new devices to the Java 3D environment and the allInputDevices method produces an enumeration that allows examining all available devices within a Java 3D environment.

9.2 Sensors

The Java 3D API provides only an abstract concept of a device. Rather it abstracts away issues of devices and device models, defining instead the concept of a sensor. A sensor consists of a time-stamped sequence of input values and the state of the buttons or switches at the time that Java 3D sampled the value. A Sensor also contains a hotspot offset specified in that sensor's local coordinate system. If not specified, the hotspot is (0.0, 0.0, 0.0).
Since a typical hardware environment contains multiple sensing elements, Java 3D maintains an array of sensors. Users can access a sensor directly from their Java code or they can assign a sensor to one of Java 3D's predefined 6DOF entities such as the UserHead.

9.2.1 Using and Assigning Sensors

Using a sensor is as easy as accessing an object. The application developer writes Java code to extract the associated sensor value from the array of sensors. The developer can then directly apply that value to an element in a scene graph or process the sensor values in whatever way necessary.
Java 3D includes three special six-degree-of-freedom (6DOF) entities. These include UserHead, DominantHand, and NondominantHand. An application developer can assign or change which sensor drives one of these predefined 6DOFs. Java 3D uses the specified sensor to drive the 6DOF entity-most visibly the View. Application developers should use this facility carefully. It is quite easy to get the effect of a WristCam-very disconcerting as well.

9.2.2 Behind the (Sensor) Scenes

Java 3D does not provide raw tracker or joystick-generated data in a sensor. At a minimum, Java 3D normalizes the raw data using the registration and calibration parameters either provided by or provided for the end user. It additionally may filter and process the data to remove noise and improve latency. The application programmer can suppress this latter effect on a sensor-by-sensor basis.
Unfortunately, tracker or sensor hardware may not always be available or be operational. Thus, Java 3D provides both an available and an enable flag on a per-sensor basis.

9.2.3 The Sensor Object

Java 3D stores its sensor array in the PhysicalEnvironment object. Each Sensor in the array consists of a fixed number of SensorRead objects. Also associated with each SensorRead is its timestamp and the state of that sensor's buttons.

Constants

The Sensor object specifies the following constants.
public static final int PREDICT_NONE
public static final int PREDICT_NEXT_FRAME_TIME
These flags define the Sensor's predictor type. The first flag defines no prediction. The second flag specifies to generate the value to correspond with the next frame time.
public static final int NO_PREDICTOR
public static final int HEAD_PREDICTOR
public static final int HAND_PREDICTOR
These flags define the Sensor's predictor policy. The first flag specifies to use no prediction policy. The second flag specifies to assume that the sensor is predicting head position or orientation. The third flag specifies to assume that the sensor is predicting hand position or orientation.
public static final int DEFAULT_SENSOR_READ_COUNT
These constant specifies the default number of SensorRead objects constructed, when no SensorRead count is specifies.

Constructors

The Sensor object specifies the following constructors.
public Sensor(InputDevice device)
public Sensor(InputDevice device, int sensorReadCount)
public Sensor(InputDevice device, int sensorReadCount, 
       int  sensorButtonCount)
These methods construct a new Sensor object associated with the specified device and consisting of either a either default number of SensorReads or sensorReadCount SensorReads and a hot spot at (0.0, 0.0, 0.0) specified in the Sensor's local coordinate system. The default for sensorButtonCount is zero.
public Sensor(InputDevice device, Point3d hotspot)
public Sensor(InputDevice device, int sensorReadCount, 
       Point3d  hotspot)
public Sensor(InputDevice device, int sensorReadCount, 
       int  sensorButtonCount, Point3d hotspot)
These methods construct a new Sensor object associated with the specified device and consisting of sensorReadCount SensorReads or a default number of SensorReads and an offset defining the Sensor's hot spot in the Sensor's local coordinate system. The default for sensorButtonCount is zero.

Methods
public int getSensorReadCount()
public int getSensorButtonCount()
These methods retrieve the number of SensorRead objects associated with this sensor and the number of buttons associated with this sensor. Both the number of Sensor Read objects and the number of buttons are determined at Sensor construction time.
public void getHotspot(Point3d hotspot)
public void setHotspot(Point3d hotspot)
These methods set and retrieve the sensor's hotspot offset. The hotspot is specified in the Sensor's local coordinate system.
public void lastRead(Transform3D read)
public void lastRead(Transform3D read, int k)
These methods extract the most recent sensor reading and the kth most recent sensor reading from the sensor object. In both cases, the methods copy the sensor value into the specified argument.
public void getRead(Transform3D read)
public void getRead(Transform3D read, long deltaT)
The first method computes the sensor reading consistent with the prediction policy and copies that value into the read matrix. The second method computes the sensor reading consistent as of time deltaT in the future and copies that value into the read matrix. All times are in milliseconds.
public long lastTime()
public long lastTime(int k)
These methods return the time associated with the most-recent sensor reading and with the kth most-recent sensor reading, respectively.
public int[] lastButtons()
public int[] lastButtons(int k)
These methods return the state of the buttons associated with the most-recent sensor reading and the kth most-recent sensor reading, respectively.
public void setPredictor(int predictor)
public int getPredictor()
These methods set and retrieve the Sensor's predictor type. The predictor type is one of: NO_PREDICTOR, HEAD_PREDICTOR, or HAND_PREDICTOR.
public void setPredictionPolicy(int policy)
public int getPredictionPolicy()
These methods set and retrieve the Sensor's predictor policy. The predictor policy is one of: PREDICT_NONE, PREDICT_NEXT_FRAME_TIME.
public void setDevice(InputDevice device)
public InputDevice getDevice()
These methods set and retrieve the Sensor's input device.
public SensorRead getCurrentSensorRead()
This method returns the current number of sensor read objects per sensor.
public void setNextSensorRead(long time, Transform3D transform, 
       int buttons[])
This method sets the next sensor read objects to the specified values, including the next SensorRead's associated time, transformation, and button state array.

9.2.4 The SensorRead Object

A SensorRead object encapsulates all the information associated with a single reading of a sensor.

Constructors

The SensorRead object specifies the following constructor.
public SensorRead())
Creates a new SensorRead object.

Methods
public final void set(Transform3D t1)
public final void get(Transform3D result)
These methods set and retrieve the read's transform3D. They allow a device to store a new rotation and orientation value into the SensorRead object and a consumer of that value to access it.
public final void setTime(long time)
public final long getTime()
These methods set and retrieve the read's timestamp. They allow a device to store a new timestamp value into the SensorRead object and a consumer of that value to access it.
public final void setButtons(int values)
public final int getButtons(int values)
These methods set and retrieve the read's button values. They allow a device to store an integer that encodes the button values into the SensorRead object and a consumer of those values to access the state of the buttons.

Java 3D API Specification

Copyright © 1997, Sun Microsystems, Inc. All rights reserved.